Server Watch Plugin API
1.0
Supports Server Watch version 3.5.x
In Server Watch, each server type is defined by a Server Plugin. The plugin's job is to go out and fetch the data from that server type, process it, and prepare it for display. In return, Server Watch provides a powerful set of classes and functions that give the plugin a great deal of free functionality. For example, Server Watch provides a table data API that allows the plugin to insert data into any number of plugin defined data tables. Server Watch can then take these tables and output them to the user. The plugin doesn't need to write any graphical interface code to make this work -- its free.
There is a lot of this free functionality in Server Watch that was developed to meet the needs of the common plugin writer, but the API is also flexible enough that, with a little extra efforf, developers can create functionality that the designers of the plugin API never imagined, but still make that funcitonality looks like it belongs in Server Watch. For example, a plugin can define a custom graphical interface pane that inserts itself into the server's list of panes and the user will interact with it exactly as they would a pane defined by Server Watch. In fact, the user won't even know there is anything different about the pane. The admin panes in many of Server Watch's plugins are examples of this capablity.
There are two types of plugins in Server Watch. The first is a standard server Plugin (usually just called plugin). This plugin provides functionality for a specific server type and has a file extension of .swplugin in its file name. The second plugin type was introduced in Server Watch 3.5 and is called a Plugin Extender (.swpluginex). This plugin type adds functionality to one or more pre-existing standard plugins. These are great if you want to extend the capabilities of a plugin that already exists, but you don't want to rewrite the existing functionality. Or, you can use it to define functionality that is used by multiple server types, thus allowing you to encapsulate that shared functionality into one plugin.
Standard server plugins and plugin extenders are developed in a very similar fashion to each other. They use many of the same classes and handle many of the same events. If you understand how to write one, it will take very little to learn how to implement the other.
All plugins must be writen in C++ and compiled on the Visual Studio .NET 2003 compiler. Other compilers may work, but have not been tested and cannot be fully supported, since we do not necessarily have access to them.
While there are no plans at this time to allow the use of another language with the Server Watch plugin API, it is possible to call other libraries or scripting languages from our plugins. In this way, you may be able to use existing libraries that are written in other languages with the Server Watch plugin API.
If you would like to see support for other languages, please contact us through our support page at
http://www.dfsoftware.com/support.html or join the Server Watch mailing list at
http://www.dfsoftware.com/maillists.html
A plugin developer can create extremely powerful plugins, but there are a few basics you need to know before you get started.
A plugin is nothing more than a traditional Windows DLL that exports a set of specific C functions that will be called by Server Watch at runtime. Each function is called in response to specific events that occur in Server Watch. These functions are defined in two files (one for each of the two plugin types).
The files in the table above fully document each function in the interface. Read through them to gain an understanding of how the interfaces work and how they will be used by Server Watch. This will give you an much better overview of the basics of what to expect as a plugin writer.
Looking through these two files, you'll notice that there are only a handful of functions in the plugin interface and that the plugin interface for a Plugin Extender is largely just a subset of a Standard Plugin. In fact, the only extra interface function that the Plugin Extender uses is
swplugindllex::DoYouExtend().
Not only are there very few functions to begin with, but many of them can be left empty unless you want to develop specific types of functionalty. In fact, our experience shows that most plugins can be developed by only filling out three or four functions:
And, of those functions, the meat of your work will occur in the Ping function. So, writing your first plugin should be a fairly simple process.
Along with the plugin interface, you will also need to setup a specific set of Windows resources in the plugin. These resources, which are mostly strings in the string table, provide Server Watch with important information like, what the name is, who the author is, and what the plugin's unique identifier (GUID) is so that it can tell it apart from other plugins. The resources and IDs that you need to complete are identified in the "Resource IDs" section of
SWMessages.h. The easiest way to guarantee that you have all of these setup correctly is to base your new plugin on one of our demonstration plugins and change the string table elements and icon to the values and image that you want.
Server Watch uses the C
Plugin Interface to communicate with your plugin. In return, your plugin will communicate with Server Watch using two classes:
ISWServerData and
ISWServerSettings. Instances of these two classes are passed into many of the functions in the
Plugin Interface encapsulated inside an
SWPluginServerStruct. When you receive an
SWPluginServerStruct from Server Watch, you can be certain that the classes in it are associated to the server that triggered the event. If the function doesn't pass one of these structures, you can be sure that the event associated with that function is not a server event.
ISWServerSettings is the class that contains the settings that the user has entered for the server. You'll find such things as the server's address and port as well as timeout information and many others. This class provides very few setting functions. Server Watch handles these values and the user interaction that set them -- the plugins shouldn't need to set them.
ISWServerData is the class that contains the runtime information for the server. This is the class you will spend most of your time interacting with. Here, you will set the values you find when your plugin pings the server. There is specific information like the status text and the auxiliary stat text. There are also more generic data output sources like Data Tables. In all cases, Server Watch will take the information you set on this class and provide the graphical display, and other related functionality, to the user for free.
When you read through the documentation for
ISWServerSettings and
ISWServerData, make sure that you pay extra attention to the concurrency section for each class. Since the Ping interface function is run within its own thread so as not to block the users interaction with Server Watch, you must follow the concurrency rules for each of these classes (they are slightly different from each other). This is not difficult once you get the hang of it, and the example projects shipped with the SDK have detailed examples of their uses.
One of the more useful data types supported by the Server Watch Plugin API is the Data Tables that are implemented in
ISWServerData. Most of the status data about a server is best managed as lists or tables of data. Data Tables are designed specifically to manage this information. Also, when you use the Data Tables in
ISWServerData to manage your list and table data, Server Watch provides the display of the data for free. This free display includes output using Server Watch's web output generation.
Plugins can define any number of Data Tables, but they can only assign one of those tables the special role of the "users table." This association is made with a call to the
ISWServerData::SetUsersTableID "SetUsersTableID()" function after the table has been created. The users table will interact with the built-in buddies functionality -- the first column of the table will be searched for buddies and the lines that match a buddy search will be marked as such in the Server Watch interface and trigger events appropriately.
Read the "Data Tables" topic in
ISWServerData for detailed information.
Many users of Server Watch rely on the Tray Icon output that Server Watch manages to quickly understand a server's status. The plugins manage what will be displayed in these icons through the
ISWServerData class.
Read the "Tray Icon" topic in
ISWServerData for detailed information.
The following flags must be set in addition to the default project settings in order for your dll to work with Server Watch:
Description | Setting | Flag |
Configuration Type | Dynamic Library (.dll) | |
Use of ATL | Dynamic Link to ATL | |
Character Set | Use Unicode Character Set | |
Use Managed Extensions | No | |
Runtime Library | Multi-threaded Debug DLL | /MDd |
Enable Function Level Linking | Yes | /Gy |
Enable Run-Time Type Info | Yes | /GR |
The plugin will also need to link to all the libraries included with the sdk in externals/Release/lib. We suggest you base your project on one of our demo projects in order to make sure that all project settings are correct.
The plugin should use Unicode instead of ASCII or double-byte strings and UNICODE and _UNICODE should both be defined at build. If you have not used this before, it is not difficult. Consult Microsoft documentation for more information. The demo projects are already setup and use Unicode strings correctly.
Server Watch uses the C++ Standard Library (STL) as a critical part of its plugin API. Because the Microsoft implementation of the STL doesn't mix debug and release libraries very well with std::wstring, you will need to use the version of Server Watch delivered in this SDK to test your plugins that build in debug. This can be found in the directory "Server Watch for Debug".
To run your debug built plugin, you can place it in "Server Watch for Debug/plugins" and then run "Server Watch for Debug/ServerWatch.exe". However, you will have to do this every time you build the plugin. To help with this, Server Watch provides a command line paramater that informs Server Watch that there is a second directory where it should look for plugins. Add the following to your projects Debugging "Command Arguments":
-plgpath="<pathtodir>"
You should replace <pathtodir> with the path to where your plugin is being built.
- Note:
- When you attempt to debug a plugin with "Server Watch for Debug/ServerWatch.exe", Visual Studio will complain that there is no debug informat in Server Watch. This is expected, and you should continue debugging.
Here is a list of links to information about advanced topics in plugin writing. These topics are not required for developing a basic plugin.
Most users want to be able to quickly join a server that they are monitoring. To help with this, Server Watch provides a powerful user interface that allows the user to set how they want to connect to that server. As the plugin writer, you can define any number of required and optional parameters that the user can set values for. You can then take these values and use them when launching the application to connect to the server.
Read the "Join Functionality" topic in
ISWServerSettings for detailed information.
Sometimes you will need to store data at runtime that is associated to a server, but Server Watch doesn't know about it. This is often the case when you are developging your own panes, because you are probably developing functionality that the Server Watch plugin API designers hadn't thought of, but they have thought of a way to store this data. Each instance of
SWPluginServerStruct has a value called pCustomData where you can store any type of data you want, and it will always be available in the
SWPluginServerStruct that is passed to your plugin during server specific events.
Read the
SWPluginServerStruct::pCustomData section for detailed information. Also read the
Using the Windows Registry "Using the Windows Registry" section to understand the correct way to store this information in the registry.
If you have custom data and custom setting for your plugin, you will probably need to save them. The Server Watch plugin API provides a class,
DFRegTool, for storing data in the registy. This class is significantly easier to use than the Windows registry APIs directly and, when used as documented, allows Server Watch to save the data in a format and location that it can manipulate and manage through enhancements to the program. If you do not use this tool to save your data to the registry, you must not save it within the Server Watch registry location, and we can't guarantee that the settings will work the way that a user expects from one Server Watch version to the next.
Read the
DFRegTool class information for detailed information.
Server Watch allows you add menu items to the context menu of the auxstat display and the users table. The items can be manipulated whenever the user right-clicks on one of those areas allowing for detailed contextual menu items. Server Watch then allows your plugin to run logic when the user selects one of your items. This is how Server Watch allows you to kick users off of certain servers by right-clicking on the user in the users table.
This capability is available to both standard plugins and plugin extenders (both can add items to the same menu at the same time). More information is avaliable in the
ISWPluginMenu interface documentation.
Server Watch provides a facility for plugins to define completely new functionality that the Server Watch developers haven't even considered, but can still look like its part of Server Watch. This facility is known as custom panes. You can define windows that, when defined appropriatly, will be hosted within Server Watch just like any other server pane. While this is not difficult, it is probably the most complicated part of Server Watch's plugin API and requires a solid understanding of how to develop a window using the Windows programming APIs.
This capability is available to both standard plugins and plugin extenders. Read the
ISWPluginPane section for detailed information. This documentation assumes that you already know how to develop graphical interfaces in windows and does not attempt to teach that information in any way. Also, you may want to review the
Custom Server Data section to see how to store data that Server Watch doesn't have pre-defined and
Using the Windows Registry do understand the appropriate way to store that data.